docs: fix openspec status examples in cli.md#761
docs: fix openspec status examples in cli.md#761fsilvaortiz wants to merge 1 commit intoFission-AI:mainfrom
Conversation
…tput The text and JSON output examples for the status command used incorrect field names, indicators, and structure. Updated to match real CLI output, validated against a test project with partial artifacts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis pull request updates CLI status documentation to align with actual command output. Changes include JSON field renames (changeName, schemaName), new fields (isComplete, applyRequires), simplified status values, and UI indicator updates. All changes are documentation-focused with no functional code modifications. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cli.md`:
- Around line 442-445: The doc has an ordering inconsistency for the
"spec-driven" flow: one section shows "proposal → design → specs → tasks" while
another shows "proposal → specs → design → tasks"; pick the correct canonical
order for the spec-driven flow (or add a short note explaining why the two
orders differ) and update all occurrences to match; search for the "spec-driven"
heading and the sequences "proposal → design → specs → tasks" and "proposal →
specs → design → tasks" (and the nearby mention affecting the section noted as
"Also applies to: 457-460") and make the text consistent or add the explicit
explanation.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.changeset/fix-cli-status-docs.mddocs/cli.mdopenspec/changes/fix-cli-status-docs/.openspec.yamlopenspec/changes/fix-cli-status-docs/design.mdopenspec/changes/fix-cli-status-docs/proposal.mdopenspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.mdopenspec/changes/fix-cli-status-docs/tasks.md
| [x] proposal | ||
| [ ] design | ||
| [x] specs | ||
| [-] tasks (blocked by: design) |
There was a problem hiding this comment.
Potential ordering inconsistency within the same doc for spec-driven flow.
This example shows proposal → design → specs → tasks, but Line 585 still says proposal → specs → design → tasks. Please align both sections (or explicitly explain why they differ).
Also applies to: 457-460
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cli.md` around lines 442 - 445, The doc has an ordering inconsistency
for the "spec-driven" flow: one section shows "proposal → design → specs →
tasks" while another shows "proposal → specs → design → tasks"; pick the correct
canonical order for the spec-driven flow (or add a short note explaining why the
two orders differ) and update all occurrences to match; search for the
"spec-driven" heading and the sequences "proposal → design → specs → tasks" and
"proposal → specs → design → tasks" (and the nearby mention affecting the
section noted as "Also applies to: 457-460") and make the text consistent or add
the explicit explanation.
There was a problem hiding this comment.
Good catch on the ordering difference — this is intentional and both are correct for their respective contexts:
- Line 585 documents the
openspec schemascommand, which shows the schema's canonical definition order:proposal → specs → design → tasks. This reflects how the schema declares its artifacts. - The status examples (lines ~437–463) document the
openspec statuscommand, which shows the topological sort order:proposal → design → specs → tasks. This reflects how the CLI actually outputs status.
specs and design are parallel — both depend only on proposal — so neither ordering is "wrong"; they just come from different sources (schema definition vs. runtime topological sort).
Since the goal of this PR is to make the status examples match the actual CLI output, the status section must use the topological sort order. Line 585 correctly reflects the schema definition order for a different command.
No change needed here.
There was a problem hiding this comment.
@fsilvaortiz, thank you for the detailed clarification! That makes complete sense now. Topological sorting can produce multiple valid orderings for graphs with parallel dependencies, and since specs and design both depend only on proposal, either order is valid depending on the context.
I appreciate you explaining the distinction:
- Schema definition order (Line 585) = how the schema artifact flow is declared
- Topological sort order (status output) = how the CLI runtime actually outputs the artifacts
Since your PR is ensuring the docs match the actual CLI behavior, using the topological sort order in the status examples is absolutely correct. Apologies for the noise on this one!
✏️ Learnings added
Learnt from: fsilvaortiz
Repo: Fission-AI/OpenSpec PR: 761
File: docs/cli.md:442-445
Timestamp: 2026-02-25T20:02:43.381Z
Learning: In the OpenSpec spec-driven schema, `specs` and `design` artifacts are parallel dependencies that both depend only on `proposal`. This means either can appear first in a topological sort, and both orderings are valid depending on the specific sort algorithm used.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Greptile SummaryFixed documentation examples in Changes made:
The changes were validated against the actual CLI implementation in Confidence Score: 5/5
Important Files Changed
Last reviewed commit: ef68ba2 |
TabishB
left a comment
TabishB
left a comment
There was a problem hiding this comment.
Hey, you don't have to produce a spec change for just a docs update. These can be made directly. A spec here doesn't really make sense anyway. Could you remove the changeset to please! Thanks!
2 participants
Summary
✓/◆/○indicators with actual[x]/[ ]/[-], addedProgress:header, fixed artifact orderchange→changeName,schema→schemaName,status: "complete"→status: "done"), added missing fields (isComplete,applyRequires,outputPath,missingDeps), removed non-existent fields (next,requires)Test plan
openspec status --change <name>— text output matches documented exampleopenspec status --change <name> --json— every field name and value matches documented example🤖 Generated with Claude Code
Summary by CodeRabbit